<HTML><HEAD><TITLE>cursor_next_tuple(++Cursor, -ResultTuple)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">library(dbi)</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>cursor_next_tuple(++Cursor, -ResultTuple)</H1>
Retrieve the next result tuple from the SQL query in ResultTuple
<DL>
<DT><EM>Cursor</EM></DT>
<DD>A cursor handle
</DD>
<DT><EM>ResultTuple</EM></DT>
<DD>Returned result tuple
</DD>
</DL>
<H2>Description</H2>
<P>
 Retrieve the next result tuple from the SQL query represented by Cursor,
 and unify it with ResultTuple. Cursor is a cursor previously created with
 session_sql_query/4 or session_sql_prepare_query/5. ResultTuple is a
 structure with the same name and arity as defined by the tuple template
 when the cursor was created. The predicate converts the result to the type
 specified in the template, except that NULL values are returned as
 variables.
</P><P>
 If the SQL query have not yet been executed, and it contains no
 parameters, then the SQL query will first be executed before retrieving
 the result.
</P><P>
 cursor_next_tuple/2 will fail when all the results tuples for the query
 have been returned. If it is then called again for the same SQL query,
 this cancels the cursor, and raise the cursor cancelled error.
</P><P>
 cursor_next_tuple/2 is not resatisfiable, so to return successive tuples
 on backtracking, use repeat/0 to re-execute cursor_next_tuple/2:
<TT><PRE>
  match_tuple(Cursor, Tuple) :-
        repeat,
        ( cursor_next_tuple(Cursor, Tuple0) ->
             Tuple0 = Tuple
        ;
             !, fail
        ).
</PRE></TT>

<H3>Fail Conditions</H3>
No more results are available for the SQL query
<H3>Resatisfiable</H3>
no
<H3>Exceptions</H3>
<DL>
<DT><EM>(5) type error </EM>
<DD>Cursor is not a valid cursor handle
<DT><EM>(5) type error </EM>
<DD>Unable to convert tuple result to ECLiPSe type
<DT><EM>(dbi_error) </EM>
<DD>Error from DBMS while executing SQL associated with Cursor.
<DT><EM>(dbi_error) </EM>
<DD>Error from DBMS while fetching result
<DT><EM>(dbi_not_query) </EM>
<DD>The SQL associated with Cursor is not a query and so cannot return results.
<DT><EM>(dbi_buffer_over) </EM>
<DD>Result value(s) too big for the buffer
<DT><EM>(dbi_cancelled) </EM>
<DD>The cursor have been cancelled.
</DL>
<H2>Examples</H2>
<PRE>
  check_overdraft_limit(Session, Account) :-
      L = ["select count(id) from accounts \
          where     id = ",Account," and balance &lt; overdraft"],
      concat_string(L,SQL),
      session_sql_query(Session,c(0),SQL,OverdraftCheck),
      cursor_next_tuple(OverdraftCheck,c(Count)),
      Count = 0.
</PRE>

</BODY></HTML>
